Set Default Card

Set a card as the default payment method for a customer

POST /api/cards/default

Set Default Card

cURL

curl --request POST \
  --url https://api.example.com/api/cards/default \
  --header 'Content-Type: application/json' \
  --data '
{
  "userId": "<string>",
  "default_source": "<string>"
}
'

200

{
  "status": true,
  "message": "<string>",
  "data": {
    "id": "<string>",
    "default_source": "<string>",
    "email": "<string>",
    "name": "<string>",
    "sources": {}
  }
}

Sets a specific card as the default payment source for a customer. This card will be used for automatic payments unless otherwise specified.

Request Body

userId · string · required

The Stripe customer ID. Must start with cus_.

Example: "cus_QRs9eKZ4xUzN2TP9"

default_source · string · required

The card ID to set as default. Must start with card_ or src_.

This must be a card that’s already attached to the customer. Use Assign Card first if needed.

Example: "card_1QRs9eKZ4xUzN2TPabcdefgh"

Response

status · boolean

Indicates if the request was successful (true) or failed (false).

message · string

Human-readable message describing the result.

Example: "Método de pago actualizado con éxito"

data · object

The updated Stripe customer object. This is the raw customer object from Stripe containing all customer information.

Show Customer Object (selected fields)

id · string

The customer’s unique identifier.

default_source · string

The ID of the default payment source for the customer.

email · string

The customer’s email address.

name · string

The customer’s full name.

sources · object

The customer’s payment sources (cards).

Example Request

cURL

curl -X POST https://your-api.com/api/cards/default \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "cus_QRs9eKZ4xUzN2TP9",
    "default_source": "card_1QRs9eKZ4xUzN2TPabcdefgh"
  }'

Example Response

200 - Success

{
  "status": true,
  "message": "Método de pago actualizado con éxito",
  "data": {
    "id": "cus_QRs9eKZ4xUzN2TP9",
    "object": "customer",
    "email": "[email protected]",
    "name": "John Doe",
    "phone": "[phone]",
    "default_source": "card_1QRs9eKZ4xUzN2TPabcdefgh",
    "created": 1710259200,
    "sources": {
      "object": "list",
      "data": [
        {
          "id": "card_1QRs9eKZ4xUzN2TPabcdefgh",
          "object": "card",
          "brand": "Visa",
          "last4": "4242",
          "exp_month": 12,
          "exp_year": 2026
        }
      ]
    }
  }
}

Use Cases

Setting Default After Card Assignment

After assigning a new card to a customer, you may want to set it as the default:

Node.js

// First, assign the card
const assignResponse = await fetch('https://your-api.com/api/cards/assign', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    userId: 'cus_QRs9eKZ4xUzN2TP9',
    source: 'tok_1QRs9eKZ4xUzN2TP9vQqWXYZ'
  })
});
const assignData = await assignResponse.json();

// Then set it as default
const defaultResponse = await fetch('https://your-api.com/api/cards/default', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    userId: 'cus_QRs9eKZ4xUzN2TP9',
    default_source: assignData.data.cardId
  })
});
const defaultData = await defaultResponse.json();
console.log('Default card set:', defaultData);

Switching Default Cards

If a customer has multiple cards and wants to switch the default:

Node.js

// Get the customer's cards first
const cardsResponse = await fetch('https://your-api.com/api/cards/cus_QRs9eKZ4xUzN2TP9');
const cardsData = await cardsResponse.json();

// User selects a different card
const selectedCardId = cardsData.data[1].id; // Second card

// Update default
const response = await fetch('https://your-api.com/api/cards/default', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    userId: 'cus_QRs9eKZ4xUzN2TP9',
    default_source: selectedCardId
  })
});

The default payment source will be automatically used for subscription charges and invoice payments when no specific payment method is provided.